home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / e / kyz_obj.lha / catalog.e < prev    next >
Text File  |  1998-09-04  |  7KB  |  231 lines
  1. OPT MODULE
  2.  
  3. MODULE 'locale', 'libraries/locale', 'utility/tagitem'
  4.  
  5. /****** catalog.m/--overview-- *******************************************
  6. *
  7. *   PURPOSE
  8. *    To act as the base class for localized ID/string pairs.
  9. *
  10. *   OVERVIEW
  11. *    The  locale  library  contains  a  mechanism for isolating textual
  12. *    strings  in  program  code (such as "OK", "Please select file" and
  13. *    other  strings  for the benefit of the user) and allowing for them
  14. *    to  be  changed  externally  from the program, while still holding
  15. *    'default'  copies of the strings in the program core. This creates
  16. *    the opportunity to have 'localized' strings.
  17. *
  18. *    The default mechanism for this is with two 'catalog' files, Bla.cd
  19. *    and Bla.ct, where the .cd file is the catalog of 'descriptors' and
  20. *    the .ct file is a catalog of translations for a specific language.
  21. *
  22. *    The .cd file contains your original text strings, and an uppercase
  23. *    identifier for each of them. Example:
  24. *
  25. *    MSG_OPEN_FILE (//)
  26. *    Open file...
  27. *
  28. *    The  identifier  is  translated into a numerical ID, and using the
  29. *    'const' / 'define'  feature  of most programming languages, the ID
  30. *    name is associated with that unique numerical value.
  31. *
  32. *    When  you  wish  to use a string in your program, you would get it
  33. *    from a function taking the ID and returning the string.
  34. *
  35. *    filereq('Open file...')
  36. *    BECOMES
  37. *    filereq(get(MSG_OPEN_FILE))
  38. *
  39. *    What  the  catalog_obj does is represent the catalog as an object,
  40. *    thereby allowing you easy use of multiple catalogs, and using even
  41. *    single  catalogs  very  easily. The general mechanism for actually
  42. *    using  catalogs  is to subclass the bare catalog object and set up
  43. *    default preset values - catalog name, builtin strings, language of
  44. *    builtin strings, and possibly version.
  45. *
  46. *   EXAMPLE
  47. *    See the included example files showing a localised 'helloworld'.
  48. *
  49. *    A  FlexCat  '.sd'  file,  included and used by the example, can be
  50. *    used for automatic generation of compiled catalog modules from .cd
  51. *    files.
  52. *
  53. ****************************************************************************
  54. *
  55. *
  56. */
  57.  
  58. OBJECT cat_str
  59.   id:LONG                 -> ID value
  60.   str:PTR TO CHAR         -> associated string
  61. ENDOBJECT
  62.  
  63. EXPORT OBJECT catalog_obj PRIVATE
  64.   cat:PTR TO catalog      -> catalog associated with this object
  65.   base:PTR TO localebase  -> locale.library base
  66.   block:PTR TO cat_str    -> the strings with their IDs
  67.   strcnt:LONG             -> total number of strings
  68. ENDOBJECT
  69.  
  70.  
  71.  
  72. /****** catalog.m/open ***************************************************
  73. *
  74. *   NAME
  75. *    catalog_obj.open() -- Constructor.
  76. *
  77. *   SYNOPSIS
  78. *    open(catalog, language, locale:PTR TO locale)
  79. *
  80. *   FUNCTION
  81. *    Creates an instance of the catalog class. Opens the locale library
  82. *    and appropriate translations of the catalog as neccesary.
  83. *
  84. *    As  no  minimum  level  of  allocations  are  necessary to operate
  85. *    correctly, this constructor throws no exceptions.
  86. *
  87. *    Apart from calling this constructor, you should also call def() to
  88. *    set up default strings before starting to call get().
  89. *
  90. *   INPUTS
  91. *    catalog  - The  name  of  the catalog containing your strings, for
  92. *               example 'helloworld.catalog'. Must not be NIL.
  93. *
  94. *    language - A  string  representing the name of the language of the
  95. *               default strings you supply - for example, 'français' or
  96. *               'deutsch'.  If  the language of the defaults strings is
  97. *               'english', you can pass NIL instead.
  98. *
  99. *    locale -   If  you  are  using  a particular locale structure from
  100. *               OpenLocale(),  you  may  pass  this  in  to  affect the
  101. *               opening and parsing of the catalog. If you just want to
  102. *               use  the default locale (user's preference) then simply
  103. *               pass NIL.
  104. *
  105. *   SEE ALSO
  106. *    locale.library/OpenCatalog(), def()
  107. *
  108. ****************************************************************************
  109. *
  110. *
  111. */
  112.  
  113. EXPORT PROC open(name, lang=NIL, locale=NIL) OF catalog_obj
  114.   DEF cat=NIL
  115.   IF localebase := OpenLibrary('locale.library', 38)
  116.     cat := OpenCatalogA(locale, name, [OC_BUILTINLANGUAGE, lang, TAG_DONE])
  117.   ENDIF
  118.   self.base := localebase
  119.   self.cat  := cat
  120. ENDPROC
  121.  
  122.  
  123. /****** catalog.m/end *******************************************
  124. *
  125. *   NAME
  126. *    catalog_obj.end() -- Destructor.
  127. *
  128. *   SYNOPSIS
  129. *    end()
  130. *
  131. *   FUNCTION
  132. *    Frees resources used by an instance of the catalog_obj class.
  133. *
  134. ****************************************************************************
  135. *
  136. *
  137. */
  138.  
  139. EXPORT PROC end() OF catalog_obj
  140.   IF localebase := self.base
  141.     CloseCatalog(self.cat)
  142.     CloseLibrary(localebase)
  143.   ENDIF
  144. ENDPROC
  145.  
  146.  
  147. /****** catalog.m/def ***************************************************
  148. *
  149. *   NAME        
  150. *    catalog_obj.def() -- Set up the default strings block.
  151. *
  152. *   SYNOPSIS
  153. *    def(block:PTR TO LONG)
  154. *
  155. *   FUNCTION
  156. *    Set the catalog's block of default strings. This is best kept as a
  157. *    static  list with constants and static strings in it - the catalog
  158. *    neither  copies  the strings nor the block into its own memory, it
  159. *    uses the block and strings direct from whatever you pass it.
  160. *
  161. *   INPUTS
  162. *    block - a list containing ID/string pairs, see the example below.
  163. *
  164. *   EXAMPLE
  165. *    CONST MSG_HELLO=100, MSG_BYE=101
  166. *    catalog.def([
  167. *      MSG_HELLO, 'Hello',
  168. *      MSG_BYE',  'Bye'
  169. *    ])
  170. *
  171. *   NOTE
  172. *    The block _must_ be terminated with a long containing NIL. Amiga E
  173. *    does  this  automatically  when you use the list operator, but not
  174. *    when  you  use  the builtin-assembler 'LONG' directive, or magic a
  175. *    list up yourself.
  176. *
  177. *    In other words, just use this as shown and you'll be fine.
  178. *
  179. *   SEE ALSO
  180. *    get()
  181. *
  182. ****************************************************************************
  183. *
  184. *
  185. */
  186.  
  187. EXPORT PROC def(block:PTR TO LONG) OF catalog_obj
  188.   self.block  := block
  189.   self.strcnt := IF block THEN Shr(ListLen(block), 1) ELSE 0
  190. ENDPROC
  191.  
  192.  
  193.  
  194. /****** catalog.m/get ***************************************************
  195. *
  196. *   NAME
  197. *    catalog_obj.get() -- Get a localized message string.
  198. *
  199. *   SYNOPSIS
  200. *    string := get(id)
  201. *
  202. *   FUNCTION
  203. *    Attempts  to  retrieve  a  string from the opened catalog with the
  204. *    requested  ID value. If not in the catalog, it will look for it in
  205. *    the  block of default strings. If not there either, it will return
  206. *    NIL.
  207. *
  208. *   INPUTS
  209. *    id - the ID value associated with the required string.
  210. *
  211. *   RESULT
  212. *    string - the  requested  string,  possibly  translated,  or NIL if
  213. *             there is no such string available.
  214. *
  215. ****************************************************************************
  216. *
  217. *
  218. */
  219.  
  220. EXPORT PROC get(id) OF catalog_obj
  221.   DEF str=NIL, block:PTR TO cat_str, cnt
  222.  
  223.   IF (block := self.block) AND ((cnt := self.strcnt)<>0)
  224.     INC cnt
  225.     WHILE cnt--
  226.       IF block.id = id THEN str := block.str
  227.       EXIT block.id++ = id
  228.     ENDWHILE
  229.   ENDIF
  230. ENDPROC IF localebase := self.base THEN GetCatalogStr(self.cat, id, str) ELSE str
  231.